Markup Burners

POST /MarkupBurner

Creates and starts a new MarkupBurner.

A MarkupBurner represents a process that runs on the server to "burn" markup into a document. The "burning" process makes the markup definitions a permanent part of a document. The server process is started by this request then a response is sent. Use the GET /MarkupBurner/{id} API below to get the status and results of an in-progress or completed MarkupBurner process.

The input required to create a MarkupBurner is two WorkFile objects; one representing the XML which defines the markup to burn, the other representing the source document on which to burn the markup. Refer to the Work Files API topic for more information.

A new document is created that contains the burned-in markup. The source document will not be modified. The new document will be made available by a new WorkFile ID.

By default, MarkupBurner objects will be automatically deleted 20 minutes after they are created.

Http Method

POST

Request Headers

Name

Value

Details

Accusoft-Affinity-Token

Affinity token returned in post response bodies for work files specified by input.documentFileId and input.markupFileId parameter in request body.

Example: "rcqmuB9pAa8+4V7fhO1SXzawy/YMQU1g8lLdNDe5l7w="

Only required if PCC is running in multi-server mode.

Parameters

None

Request Body

In the request body, provide JSON containing the following properties:

Name	Description	Details
input.documentFileId	The ID of the WorkFile that represents the document to burn in the markup. This document will not be modified.	string, required Example: ek5Zb123oYHSUEVx1bUrVQ
input.markupFileId	The ID of the WorkFile that represents the XML document which contains the markup definition.	string, required Example: aQ1BdViqmUisBuevJKO9Sw
minSecondsAvailable	The minimum number of seconds which this MarkupBurner must remain available. If not provided, a configurable default value is used. This value is ignored if it is shorter than the configurable value.	integer, optional Example: 60

Response Body

If successful, this method returns JSON containing the following properties:

Name	Description	Details
input.documentFileId	The ID of the WorkFile that represents the document to burn in the markup. This document will not be modified. This is an echo of what was passed in by the request.	string Example: ek5Zb123oYHSUEVx1bUrVQ
input.markupFileId	The ID of the WorkFile that represents the XML document which contains the markup definition. This is an echo of what was passed in by the request.	string Example: aQ1BdViqmUisBuevJKO9Sw
expirationDateTime	The date and time (in ISO 8601 Extended Format) when the MarkupBurner will be deleted.	string Example: "2014-05-13T20:38:39.796Z"
processId	The ID of the MarkupBurner.	string Example: ElkNzWtrUJp4rXI5YnLUgw
state	The current state of the markup burning process running on the server. This will always be "processing" in this response.	string ("processing" \| "complete" \| "error" ) Example: "processing"
percentComplete	The percentage (0 – 100) complete of the markup burning process. This will always be 0 in this response.	integer Example: 0
errorCode	An error code string if a problem occurred during the markup burning process. This will always be null in this response.	string Example: null
output.documentFileId	The ID of the new WorkFile that represents a new document with markup burned into it. This will always be null in this response.	string
affinityToken	Affinity token echoed from request header. This value will only be present if PCC is running in multi-server mode.	string Example: "rcqmuB9pAa8+4V7fhO1SXzawy/YMQU1g8lLdNDe5l7w="

Status Codes

200 OK, if MarkupBurner was created successfully.
400 Bad Request, if input.documentFileId, input.markupFileId is missing or invalid format, if minSecondsAvailable is not a number.
405 Method Not Allowed, if POST HTTP method is not used.

Examples

Example Request	Copy Code
POST http://localhost:18681/PCCIS/V1/MarkupBurner Content-Type: application/json { "input": { "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ", "markupFileId": "aQ1BdViqmUisBuevJKO9Sw" }, "minSecondsAvailable": 60 }

Example Request

Copy Code

POST http://localhost:18681/PCCIS/V1/MarkupBurner
Content-Type: application/json
{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
    },
    "minSecondsAvailable": 60
}

Example Response	Copy Code
200 OK Content-Type: application/json { "input": { "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ", "markupFileId": "aQ1BdViqmUisBuevJKO9Sw" }, "expirationDateTime": "2014-12-17T20:38:39.796Z", "processId": "ElkNzWtrUJp4rXI5YnLUgw", "state": "processing", "percentComplete": 0, "errorCode": null, "output": null }

Example Response

Copy Code

200 OK
Content-Type: application/json
{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "processing",
    "percentComplete": 0,
    "errorCode": null,
    "output": null

}

GET /MarkupBurner/{MarkupBurnerId}

Gets the status and result of an existing MarkupBurner.

Requests can be sent to this URL repeatedly while state is "processing".

When state is "complete", the new document with burned-in annotations will be made available by a new WorkFile ID in the output.documentFileId. Refer to the Work Files API topic to find out how to download a WorkFile.

If the markup burning process encountered an error, the state property will be "error", the errorCode property will contain an error code string and output will be null.

Http Method

GET

Request Headers

Name

Value

Details

Accusoft-Affinity-Token

Affinity token returned in post response body for markup burner specified by MarkupBurnerId parameter in URI.

Example: "rcqmuB9pAa8+4V7fhO1SXzawy/YMQU1g8lLdNDe5l7w="

Only required if PCC is running in multi-server mode.

Parameters

Name

Description

Details

MarkupBurnerId

The ID of the MarkupBurner.

string, required

Example: ElkNzWtrUJp4rXI5YnLUgw

Request Body

None

Response Body

If successful, this method returns JSON containing the following properties:

Name	Description	Details
input.documentFileId	The ID of the WorkFile that represents the document to burn in the markup. This document will not be modified.	string Example: ek5Zb123oYHSUEVx1bUrVQ
input.markupFileId	The ID of the WorkFile that represents the XML document which contains the markup definition.	string Example: aQ1BdViqmUisBuevJKO9Sw
expirationDateTime	The date and time (in ISO 8601 Extended Format) when the MarkupBurner will be deleted.	string Example: "2014-05-13T20:38:39.796Z"
processId	The ID of the MarkupBurner.	string Example: ElkNzWtrUJp4rXI5YnLUgw
state	The current state of the markup burning process running on the server.	string ("processing" \| "complete" \| "error" ) Example: "complete"
percentComplete	The percentage (0 – 100) complete of the markup burning process. Note: The percent complete will only ever be 0 or 100.	integer Example: 100
errorCode	An error code string if a problem occurred during the markup burning process.	string Example: "DocumentFileIdDoesNotExist"
output.documentFileId	The ID of the new WorkFile that represents a new document with markup burned into it.	string Example: vry3FPE0zQqYwhzndRccOQ
affinityToken	Affinity token echoed from request header. This value will only be present if PCC is running in multi-server mode.	string Example: "rcqmuB9pAa8+4V7fhO1SXzawy/YMQU1g8lLdNDe5l7w="

Status Codes

200 OK, if MarkupBurner was retrieved successfully.
404 Not Found, if MarkupBurnerId does not exist.
405 Method Not Allowed, if GET HTTP method is not used.

Error Codes

DocumentFileIdError - This indicates that an error occurred attempting to access the document via the WorkFile Service. The specified workfile Id is valid, but an error prevented the file from being read.
DocumentFileIdDoesNotExist - This error indicates that the document requested by the specified workfile Id does not exist.
MarkupFileIdError - This indicates that an error occurred attempting to access the markup file via the WorkFile Service. In this case, the workfile Id is valid, but an error prevented the file from being read.
MarkupFileIdDoesNotExist - This error indicates that the markup file requested by the specified workfile Id does not exist.
RedactionError - This indicates a general error in creating a redacted document. Possible causes include failure to achieve an intermediate conversion, failure to delete an intermediate conversion, or failure to create the redacted output document.
RedactionWorkFileCreationError - This indicates the markup burner failed to store the final redacted output file via the workfile service.

Examples

Example Request	Copy Code
GET http://localhost:18681/PCCIS/V1/MarkupBurner/ElkNzWtrUJp4rXI5YnLUgw

Example Response	Copy Code
200 OK Content-Type: application/json { "input": { "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ", "markupFileId": "aQ1BdViqmUisBuevJKO9Sw" }, "expirationDateTime": "2014-12-17T20:38:39.796Z", "processId": "ElkNzWtrUJp4rXI5YnLUgw", "state": "complete", "percentComplete": 100, "errorCode": null, "output": { "documentFileId": "vry3FPE0zQqYwhzndRccOQ" }, }

Example Response

Copy Code

200 OK
Content-Type: application/json
{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "complete",
    "percentComplete": 100,
    "errorCode": null,
    "output": {
        "documentFileId": "vry3FPE0zQqYwhzndRccOQ"
    },
}

POST /PCCIS/V1/ViewingSession/u{ViewingSessionID}/MarkupBurner

Starts a new MarkupBurner using the source document of a viewing session and a provided XML markup definitions file as input. When the asynchronous process is ultimately finished, the output will be a new document which includes the provided markup as part of the document itself (the original source document of the viewing session is left unaltered).

This is a specialized URL which allows you to do markup burning against the source file of an existing viewing session without needing to use the work file API.

This request merely begins the markup burning process. Once started, you poll the status of the process using the GET /ViewingSession/u{ViewingSessionID}/MarkupBurner/{processId} URL below to know when the process has completed.

HTTP Method

POST

Parameters

None

Request Body

The body of the request should be XML defining the markup that needs to be burned into a copy.

Response Body

If successful, a JSON object which may contain:

Name	Description	Details
processId	The id of the process.	string Example: "ElkNzWtrUJp4rXI5YnLUgw"
state	The current state of the process. This will always be "processing" in the initial POST response.	string Example: "processing"
percentComplete	The percentage (0 - 100) complete of the process. This will always be 0 in the initial POST response.	integer Example: 0

Status Codes

200 OK, if MarkupBurner was created successfully.
405 Method Not Allowed, if POST HTTP method is not used.

Examples

Example Request	Copy Code
POST https://localhost:18681/PCCIS/V1/ViewingSession/u{ViewingSessionID}/MarkupBurner <<XML markup data>>

Example Response	Copy Code
200 OK Content-Type: application/json { "processId": "ElkNzWtrUJp4rXI5YnLUgw", "state": "processing", "percentComplete": 0 }

GET /PCCIS/V1/ViewingSession/u{ViewingSessionID}/MarkupBurner/{processId}

Gets the status of a MarkupBurner for a viewing session.

Requests are typically sent to this URL repeatedly as long as the state is "processing".

When state is "complete", a new document with the provided markup burned into it will be available at:

GET /PCCIS/V1/ViewingSession/u{ViewingSessionID}/MarkupBurner/{processId}/Document

If an error occurred and the output could not be created, the state property will be "error" and the errorCode property will contain an error code string.

HTTP Method

GET

Parameters

None

Request Body

None

Response Body

If successful, a JSON object which may contain:

Name	Description	Details
processId	The id of the process.	string Example: "ElkNzWtrUJp4rXI5YnLUgw"
state	The current state of the process.	string ("processing" \| "complete" \| "error") Example: "complete"
percentComplete	The percentage (0 - 100) complete of the process.	integer Example: 100
errorCode	An error code string if a problem occurred during processing.	string

Status Codes

200 OK, if the status of the MarkupBurner could be returned.
404 Not Found, if either the viewing session or MarkupBurner do not exist.
405 Method Not Allowed, if GET method is not used.

Examples

Example Request	Copy Code
GET http://localhost:18681/PCCIS/V1/ViewingSession/ uDLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/ MarkupBurner/5rGUUh3Qxhf6VXm8RkBPfA

Example Response	Copy Code
200 OK Content-Type: application/json { "processId": "5rGUUh3Qxhf6VXm8RkBPfA", "state": "complete", "percentComplete": 100 }

GET /PCCIS/V1/ViewingSession/u{ViewingSessionID}/MarkupBurner/{processId}/Document?ContentDispositionFilename

Gets the output result of a MarkupBurner process for a viewing session.

HTTP Method

GET

Parameters

Name

Description

Details

ContentDispositionFilename

The filename, without extension, to use in the Content-Disposition header of the response (the file extension will automatically be added).

The default value is "document".

string, optional

Request Body

None

Status Codes

404 Not Found, which may occur if any of the following are true:
- the MarkupBurner has not completed yet
- no such MarkupBurner exists
- no such viewing session exists

405 Method Not Allowed, if GET method is not used.

Examples

Example Request	Copy Code
GET https://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/MarkupBurner/ElkNzWtrUJp4rXI5YnLUgw/Document

Example Response	Copy Code
200 OK <<PDF data>>